This field provides an identifying 'name' for the answer to the current question. It is used to save the collected variable that later may be referred to by its 'name'. Often an answer saved in this manner is used in the text field of a subsequent question. Symbols can also be used dynamically in the Hard Min, Hard Max, Soft Min, and Soft Max fields. Their valuses can also be transferred into an Information Sheet for future rounds. When symbols are used in the text field of questions, in the hard min and max fields, and the soft min and max field they must be enclosed in curly brackets { }.
Symbols are declared in the Save Symbol field and used dynamically in the Text, Hard Min / Max, and Soft Min / Max field(s). An error message will appear when a user tries to leave a question with missing curly braces in the Save Symbol, Hard Min/Max or Soft Min/Max field(s). However, the Designer does NOT check the question text field for missing curly braces, because there is no way to tell whether a word is intended to be a symbol or not. Examples of valid symbol syntax in the fields where symbols are used are shown in the following table. Note how the Text field representation differs from other fields in some cases.
| Field used | Syntax examples | ||||
|---|---|---|---|---|---|
| Save Symbol | {LINTDATE} | {CURDATE} | {bdate} | {^child.name()^} | {*child.age()*} |
| Text | {LINTDATE} | {CURDATE} | {bdate} | {child.name()} | {child.age()} |
| Hard Min, Hard Max | {LINTDATE} | {CURDATE} | {bdate} | {^child.name()^} | {*child.age()*} |
Symbols Names
The following characters and special characters are allowed in symbol names.
The top line describes the syntax attributes.
The middle line describes what the lower line 'symbolizes', respectively.
| Begin Symbol |
Optional Array |
Begin Name |
These characters in any order | Depricated __?? | Optional Index |
Nesting Depth (≤3) |
Optional Index |
Optional Array |
End Symbol |
||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| open brace | caret | characters | numbers | underscore | hypen | left-bracket | right-bracket | open paren | colon | close paren | caret | close brace | |
| { | ^ | A,a - Z,z | 0 - 9 | _ | - | [ | ] | ( | : | ) | ^ | } | |
Copying and Pasting Symbol Names
When copying or pasting from an old instrument to a new instrument, characters that were allowed in the old instrument but not allowed in new instrument will be changed to _ (underscore) automatically. For example, copying a question named HE/SHE in an old instrument to a new instrument, HE/SHE will be changed to HE_SHE. If you have a symbol, named #_EMPLOYEE, in an old instrument, it will be changed to __EMPLOYEE (double underscore) in a new instrument, because # is not allowed.
Symbols allow the user to refer to variables dynamically. The CAPI Designer-Survey allows robust use of symbols. A datum can be collected or created and stored as a variable to be used later in a substitution, reference, counter, index, and/or a dynamic pick list.
The carat '^' in symbol names
Symbols and loops may be combined to create an 'array', that is, an indexed substitution or reference to a variable in nested loops. A carat (^) surrounding the symbol indicates it is part of an array. Parentheses denote the index. An array may be indexed to three levels deep. The colon (:) is used to distinguish among indexing levels of an array.
__?? * depricated below __?? The asterisk '*' in symbol names
An asterisk (*) surrounding a symbol's name indicates that the symbol is a reference to a roster or roster field. When a symbol is used in the Text field of a question, the Hard Min / Max and Soft Min / Max fields, it must be enclosed in curly braces, { }, e.g., {variable_text.extension()} or {symbol_name}. In the Designer, the symbol’s syntax is:
During Input mode, there is no way currently to view a list of symbols used in the survey during the edit process. However, to find out what symbols are missing in the survey, use the diagnostics function under Tools | Diagnostics | CAPI Diagnostics and in the "Run Diagnostics" list check the diagnostic "Missing / invalid {Symbol} or [Qname]" box. Then click the "Run" button.